home *** CD-ROM | disk | FTP | other *** search
/ Aminet 7 / Aminet 7 - August 1995.iso / Aminet / dev / c / MemPools1_2.readme < prev    next >
Text File  |  1995-07-02  |  7KB  |  194 lines
  1. Short:    Malloc() replacement using Exec pools
  2. Author:   jochen.wiedmann@uni-tuebingen.de
  3. Uploader: jochen.wiedmann@uni-tuebingen.de
  4. Type:     dev/c
  5.  
  6.  
  7. MemPools - malloc() replacement using standard Exec memory pools
  8. ================================================================
  9.  
  10.  
  11. Many people don't like using malloc() and similar functions because
  12. they think it's too slow and gives too much overhead. Well, as far as
  13. I can say they're alright, at least for users of Dice and SAS/C:
  14. The Exec pool functions seem to be at least 5 times faster and it
  15. can even be faster than the malloc() of GNU C! (See "Timings" below.)
  16.  
  17. Other people like malloc(): It's portable and rather easy to use.
  18. I am one of these, however I don't want to loose the speed of
  19. pool functions.
  20.  
  21. The mempools package is a link library with the functions malloc(),
  22. calloc(), realloc(), strdup() and free(). It replaces the compilers
  23. own functions by just linking against this library. No additional
  24. work is required as the library takes use of the compilers auto-
  25. initialization facility.
  26.  
  27. Ths autoinitialization restricts use of the mempools library to
  28. users of Dice, SAS/C and gcc: I don't know how to handle other
  29. compilers.
  30.  
  31. Note, that pools are available not only for users of OS 3.x! The
  32. current amiga.lib offers replacements which call exec.library,
  33. if the OS is 3.x and emulate pools otherwise. The MemPools
  34. library uses this replacements.
  35.  
  36.  
  37. A debugging possibility very similar to Mungwall is integrated into
  38. the library, which is enabled by compiling with -DDEBUG. The makefiles
  39. provide a target "mempoolsd.lib" which does just that.
  40.  
  41.  
  42. 1.) Disclaimer: Copyrights, (No) Warranty
  43. -----------------------------------------
  44.  
  45. This program is Copyright (C) 1994  Jochen Wiedmann
  46.                     Am Eisteich 9
  47.                     72555 Metzingen
  48.                     Germany
  49.  
  50.                     Phone: (0049) +7123 / 14881
  51.                     Mail: jochen.wiedmann@uni-tuebingen.de
  52.  
  53.  
  54. Permission is granted to make and distribute either verbatim and modified
  55. copies of this documentation and the library MemPools provided the copyright
  56. notice and this permission notice are preserved on all copies and the "GNU
  57. General Public License" (in the file COPYING) is distributed as well.
  58.  
  59. The author gives ABSOLUTELY NO warranty that the software described in this
  60. documentation and the results produced by them are correct. The author
  61. cannot be held responsible for ANY damage resulting from the use of this
  62. software.
  63.  
  64.  
  65. 2.) Installation
  66. ----------------
  67.  
  68. There are four libraries included in the distribution, it depends
  69. on your compiler which one you need: mempoolss.lib and mempoolssr.lib
  70. are for dice, they should be copied to DLIB: or a similar place.
  71. mempools.lib is for SAS/C, its destination is sc:lib. Finally
  72. libmempools.a is the GNU-c version which should go to GNU:lib.
  73.  
  74. If you want to recreate them, just type smake (SAS/C) or make (GNU-c).
  75. Dice, however, requires different libraries, depending on the data
  76. model, the type of argument handling and so on.
  77.  
  78. To create a certain library just type
  79.  
  80.     lbmake mempools s           (for mempoolss.lib)
  81.     lbmake mempools s r         (for mempoolssr.lib)
  82.     lbmake mempools l           (for mempoolsl.lib)
  83.     lbmake mempools d s         (for mempoolsds.lib)
  84.         .
  85.         .
  86.         .
  87.  
  88.  
  89. 3.) Usage
  90. ---------
  91.  
  92. All you have to do is to link against the mempools or mempoolsd library.
  93.  
  94. a) Dice
  95.  
  96.     Add the option -lmempools to your compiler statement. By adding
  97.     it to the environment variable "DCCOPTS" you get this automatically.
  98.  
  99. b) SAS/C
  100.  
  101.     Add the option LIB mempools to your compiler statement. By using
  102.     the "scopts" program you can get this automatically, too.
  103.  
  104. c) gcc
  105.  
  106.     Add the option -lmempools to your compiler statement. I don't know
  107.     if gcc can handle this automatically. Probably someone can
  108.     enlighten me?
  109.  
  110. However, you might be interested in controlling the pools attributes.
  111. This can be done by creating global variables __MemPoolPuddleSize,
  112. __MemPoolThreshSize and __MemPoolFlags which correspond to the
  113. arguments of the CreatePool() function. For example, if you want
  114. to modify the puddle size (this can increase speed, see "Timings"
  115. below), just add the following line somewhere to your program:
  116.  
  117.     ULONG __MemPoolPuddleSize = 16384;  /*  Default: 4096       */
  118.  
  119. Or if you want malloc() to obtain chip memory, just write
  120.  
  121.     #include <exec/memory.h>
  122.     ULONG __MemPoolFlags = MEMF_CHIP;   /*  Default: MEMF_ANY   */
  123.  
  124.  
  125. If you don't have amiga.lib, version 39 or later, you will miss
  126. functions like LibAllocPooled(), LibCreatePool() and so on. In that
  127. case you might wish to compile the file pools.c and add it to the
  128. library. It contains functions, that call the respective Exec
  129. functions in OS 39 or later and emulate them otherwise. However,
  130. please note, that I did *NEVER* do some serious checks on them. I have
  131. just retyped them from a german magazine.
  132.  
  133.  
  134.  
  135. 4.) Timings
  136. -----------
  137.  
  138. I wrote a little timing program. (I don't claim that it is very good,
  139. probably someone can write a better one.) I was rather surprised about
  140. the results:
  141.  
  142.     Compiler    Time (Mins:Secs)    Notes
  143.  
  144.     Dice        2:46,74             Dice maps malloc() to AllocMem()
  145.                     directly. This is extremely poor!
  146.                     Especially the exit() function
  147.                     needs about 20% of the programs
  148.                     time.
  149.  
  150.     SAS/C       1:17,66             SAS/C uses an own pool system.
  151.                     Thus the exit() function is
  152.                     rather fast. malloc(), however,
  153.                     seems to be slow.
  154.  
  155.     gcc         0:12,84 (ixemul)    gcc uses a pool system which is
  156.         0:14,34 (libnix)    rather close to Exec pools. This
  157.                     gives good results.
  158.  
  159.     MemPools    0:15,10 (4096)      By increasing the puddle size
  160.         0:12,14 (8192)      (see "Usage") you get better
  161.         0:10,80 (16384)     results! It seems worth to try a
  162.                     little bit.
  163.  
  164.  
  165. ============================= Archive contents =============================
  166.  
  167. Original  Packed Ratio    Date     Time    Name
  168. -------- ------- ----- --------- --------  -------------
  169.     1547     806 47.8% 22-May-95 08:51:16 +calloc.c
  170.    17982    6993 61.1% 26-Mar-95 20:18:20 +COPYING
  171.     3534    1322 62.5% 22-May-95 08:53:12 +DMakefile
  172.     2285    1100 51.8% 22-May-95 08:51:26 +free.c
  173.     3499    1513 56.7% 22-May-95 08:51:36 +init.c
  174.     1570     596 62.0% 02-May-95 15:33:04 +lib.def
  175.     2742     892 67.4% 10-May-95 16:41:06 +libmempools.a
  176.     3456    1278 63.0% 22-May-95 08:50:34 +Makefile
  177.     2101    1032 50.8% 22-May-95 08:51:04 +malloc.c
  178.       59      59  0.0% 26-Mar-95 20:18:22 +MemPoolFlags.c
  179.       60      60  0.0% 26-Mar-95 20:18:22 +MemPoolPuddleSize.c
  180.     2055     992 51.7% 10-May-95 16:43:44 +mempools.h
  181.     1468     666 54.6% 22-May-95 08:57:54 +mempools.lib
  182.     5637    2482 55.9% 22-May-95 08:55:02 +MemPools.readme
  183.     2044     738 63.8% 22-May-95 08:55:58 +mempoolss.lib
  184.     1984     719 63.7% 22-May-95 08:56:48 +mempoolssr.lib
  185.       59      59  0.0% 26-Mar-95 20:18:22 +MemPoolThreshSize.c
  186.     5031    1612 67.9% 10-May-95 14:02:54 +Pools.c
  187.     1756     883 49.7% 22-May-95 08:52:30 +realloc.c
  188.     2948    1176 60.1% 22-May-95 08:50:44 +SMakefile
  189.     1522     796 47.7% 22-May-95 08:52:42 +strdup.c
  190.     5029    1826 63.6% 02-May-95 13:51:04 +TimeMem.c
  191.     2861    1308 54.2% 26-Mar-95 20:18:20 +TimeProg.c
  192. -------- ------- ----- --------- --------
  193.    71229   28908 59.4% 13-Jun-95 08:22:16   23 files
  194.